<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: howl.interact</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_api doc_api_interact'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../'>Howl 0.3 Documentation</a></li><li>Api</li><li>howl.interact</li></ol>
      <h1 id="howl.interact">howl.interact</h1>    <div class="toc">
      <div class="toc-title">
        <span>howl.interact</span>
      </div>
      <div class="toc-entries">
<div class="toc-group">
<a href="#overview" class="toc-group-header overview">Overview</a>
</div>
<div class="toc-group">
<a href="#functions" class="toc-group-header functions">Functions</a>
<li class=""><a href="#register">register </a></li>
<li class=""><a href="#unregister">unregister </a></li>
</div>
<div class="toc-group">
<a href="#built-in-interactions" class="toc-group-header built-in_interactions">Built-in interactions</a>
<li class=""><a href="#read_text">read_text </a></li>
<li class=""><a href="#select">select </a></li>
<li class=""><a href="#select_buffer">select_buffer </a></li>
<li class=""><a href="#select_directory">select_directory </a></li>
<li class=""><a href="#select_file">select_file </a></li>
<li class=""><a href="#select_file_in_project">select_file_in_project </a></li>
<li class=""><a href="#select_line">select_line</a></li>
<li class=""><a href="#select_location">select_location</a></li>
<li class=""><a href="#yes_or_no">yes_or_no </a></li>
</div>
</div>
</div>
&#x000A;&#x000A;<h2 id="overview">Overview</h2>&#x000A;&#x000A;<p>The howl.interact module acts as the central registry of interactions in Howl&#x000A;and lets you register new interactions as well as invoke interactions. An&#x000A;interaction is a piece of functionality that is invoked as a function call and&#x000A;it retrieves some information from the user. Interactions use the command line,&#x000A;and optionally additional widgets, to get information from the user. For&#x000A;example, consider this call to the <code>read_text</code> interaction:</p>&#x000A;<pre class="highlight moonscript"><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">interact</span><span class="p">.</span><span class="n">read_text</span><span class="w"> </span><span class="ss">prompt:</span><span class="w"> </span><span class="s1">'Enter your name:'</span><span class="w">&#x000A;</span></pre>&#x000A;<p>Here the <code>read_text</code> interaction displays the given prompt in the command line&#x000A;and lets the user type some text. When the user presses <code>enter</code>, the command&#x000A;line is closed and the <code>read_text</code> function returns the text entered by user. If&#x000A;the user presses <code>escape</code>, the function returns <code>nil</code>.</p>&#x000A;&#x000A;<p>Interactions are commonly used to read user input when implementing interactive&#x000A;<a href="command.html">commands</a>. Howl includes a number of built-in interactions, such&#x000A;as <code>select_file</code>, which lets the user choose a file, and <code>select</code>, which lets&#x000A;the user choose an item from a list of options - see <a href="#built-in-interactions">Built-in&#x000A;interactions</a> below for details.</p>&#x000A;&#x000A;<p>An interaction is implemented as simple table that provides the name of the&#x000A;interaction, a description, and either a handler or a factory field. Simple&#x000A;interactions that just customize other interactions can be implemented easily&#x000A;with just a <em>handler</em> function. More complex interactions that need greater&#x000A;control on the command line behavior are implemented as <em>factory</em> based&#x000A;interactions. Details for both handler and factory based interactions are in&#x000A;<a href="#register">register</a> below.</p>&#x000A;&#x000A;<p>Interactions are run by the <a href="ui/command_line.html">command line</a>, which maintains a stack of running&#x000A;interactions. While one or more interactions are running, the command line API&#x000A;can be used to display prompts in the command line, read and update the command&#x000A;line text, as well as attach helper widgets above the command line (for example,&#x000A;a <a href="ui/list_widget.html">ListWidget</a> may show a completion list).</p>&#x000A;&#x000A;<hr>&#x000A;&#x000A;<p><em>See also:</em></p>&#x000A;&#x000A;<ul>&#x000A;<li>The <a href="ui/command_line.html">CommandLine</a> module for details about the command&#x000A;line API</li>&#x000A;<li>The <a href="command.html">command</a> module for more information about commands in Howl</li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="functions">Functions</h2>&#x000A;&#x000A;<h3 id="register">register <span class="arg-list">(def)</span></h3>&#x000A;&#x000A;<p>Registers a new interaction. Registered interactions are available as fields on&#x000A;the <code>interact</code> module itself, using the interaction name.</p>&#x000A;&#x000A;<p><code>def</code> is a table with the following fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>name</code>: <em>[required]</em> The name of the interaction.</li>&#x000A;<li><code>description</code>: <em>[required]</em> A short description of the interaction.</li>&#x000A;<li><code>handler</code> or <code>factory</code>: <em>[required]</em> One of <code>handler</code> or <code>factory</code> must be&#x000A;specified, but not both.</li>&#x000A;</ul>&#x000A;&#x000A;<p>The <code>handler</code> function implements the interaction and returns the result of the&#x000A;interaction. Here is an example definition of a handler:</p>&#x000A;<pre class="highlight moonscript"><span class="w">  </span><span class="ss">handler:</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">interact</span><span class="p">.</span><span class="nb">select</span><span class="w"> </span><span class="ss">items:</span><span class="w"> </span><span class="p">{</span><span class="s1">'red'</span><span class="p">,</span><span class="w"> </span><span class="s1">'blue'</span><span class="p">,</span><span class="w"> </span><span class="s1">'green'</span><span class="p">}</span><span class="w">&#x000A;</span></pre>&#x000A;<p>The above handler displays a selection list containing three items and lets the&#x000A;user select one. Note that it reuses the <code>select</code> interaction. Handler functions&#x000A;are <em>blocking</em> - i.e. the function does not return until the result of the&#x000A;interaction is available.</p>&#x000A;&#x000A;<p>The handler function may accept arguments. Any arguments passed when calling the&#x000A;interaction are passed through to the handler function.</p>&#x000A;&#x000A;<p>Interactions can also be implemented as <em>factory</em> based interactions. The&#x000A;<code>factory</code> field is a function that returns an interaction instance table. This&#x000A;table describes how various events should be handled and has the following&#x000A;fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>run</code>: <em>[required]</em> A function that is called when the interaction is invoked.&#x000A;This function is called with a <code>finish</code> callback function as the first argument,&#x000A;followed by all arguments that were passed in the interaction call. The command&#x000A;line is displayed and holds the cursor while the interaction is active. The&#x000A;interaction must call <code>finish</code> whenever the result of the interaction is ready&#x000A;and it must pass the result as the argument to <code>finish</code>. The interaction is&#x000A;active until <code>finish</code> is called, so it is important to call <code>finish</code> at some&#x000A;point.</li>&#x000A;<li><p><code>on_update</code>: <em>[optional]</em> A function that is called every time the text in the&#x000A;command line is updated. The interaction instance table and the new text are&#x000A;passed as two arguments to the function.</p>&#x000A;&#x000A;<p>If the <a href="ui/command_line.html">command line</a> API is used to update the command line text from within&#x000A;the <code>run</code> or the <code>on_update</code> function then <code>on_update</code> is not called. However,&#x000A;if the command line text is updated when the user types some text, or from&#x000A;within a keymap function, <code>on_update</code> is called.</p></li>&#x000A;<li><p><code>keymap</code>: <em>[optional]</em> A <a href="bindings.html">keymap</a> that is used while the&#x000A;interaction is active. This table specifies a mapping from keystroke names to&#x000A;functions. When a key matching the keystroke name is pressed, the function is&#x000A;invoked and the interaction instance table is passed as the first argument.</p></li>&#x000A;</ul>&#x000A;&#x000A;<p>Here is an example implementation of an interaction using a factor:</p>&#x000A;<pre class="highlight moonscript"><span class="w">  </span><span class="ss">factory:</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p">{</span><span class="w">&#x000A;    </span><span class="ss">run:</span><span class="w"> </span><span class="p">(</span><span class="vi">@finish</span><span class="p">)</span><span class="w"> </span><span class="o">=&gt;</span><span class="w">&#x000A;      </span><span class="vi">@command_line</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">app</span><span class="p">.</span><span class="n">window</span><span class="p">.</span><span class="n">command_line</span><span class="w">&#x000A;      </span><span class="vi">@command_line</span><span class="p">.</span><span class="n">prompt</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'Text:'</span><span class="w">&#x000A;&#x000A;    </span><span class="ss">on_update:</span><span class="w"> </span><span class="p">(</span><span class="n">text</span><span class="p">)</span><span class="w"> </span><span class="o">=&gt;</span><span class="w">&#x000A;      </span><span class="n">log</span><span class="p">.</span><span class="n">info</span><span class="w"> </span><span class="n">text</span><span class="w">&#x000A;&#x000A;    </span><span class="ss">keymap:</span><span class="w">&#x000A;      </span><span class="ss">enter:</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">self</span><span class="p">.</span><span class="n">finish</span><span class="w"> </span><span class="vi">@command_line</span><span class="p">.</span><span class="n">text</span><span class="w">&#x000A;      </span><span class="ss">escape:</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">self</span><span class="p">.</span><span class="n">finish</span><span class="o">!</span><span class="w">&#x000A;      </span><span class="ss">binding_for:</span><span class="w">&#x000A;        </span><span class="p">[</span><span class="s1">'view-close'</span><span class="p">]:</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="n">self</span><span class="p">.</span><span class="n">finish</span><span class="o">!</span><span class="w">&#x000A;  </span><span class="p">}</span><span class="w">&#x000A;</span></pre>&#x000A;<p>The above example displays &lsquo;Text:&rsquo; as the command line prompt and lets the user&#x000A;enter any text in the command line. Whenever the text is updated by the user,&#x000A;the interaction shows it in an info message. When the user presses <code>enter</code>, the&#x000A;interaction finishes, returning the text entered by the user. If the user&#x000A;presses <code>escape</code>, the interaction finishes, returning <code>nil</code>.</p>&#x000A;&#x000A;<p>Note the special key called <code>binding_for</code> in the keymap. This demonstrates how a&#x000A;keystroke can be specified <a href="bindings.html#indirect-bindings">indirectly</a> instead&#x000A;of by hard-coding. In the above example, the &ldquo;view-close&rdquo; key within&#x000A;&ldquo;binding-for&rdquo; refers to the keystroke currently bound to the &ldquo;view-close&rdquo;&#x000A;command. This means if the user presses the keystroke that is bound to the&#x000A;&ldquo;view-close&rdquo; command - which is <code>alt_w</code> by default - the associated function&#x000A;will be invoked, closing the command line and returning <code>nil</code>. If the user has&#x000A;changed the key binding for the &ldquo;view-close&rdquo; command, that keystroke will be&#x000A;bound to the function above instead.</p>&#x000A;&#x000A;<h3 id="unregister">unregister <span class="arg-list">(name)</span></h3>&#x000A;&#x000A;<p>Unregister an interaction with the name <code>name</code>.</p>&#x000A;&#x000A;<h2 id="built-in-interactions">Built-in interactions<a name="builtin"></a></h2>&#x000A;&#x000A;<h3 id="read_text">read_text <span class="arg-list">(opts)</span></h3>&#x000A;&#x000A;<p>Lets the user enter free form text in the command line. Returns the text entered&#x000A;by the user when the user presses <code>enter</code>, or <code>nil</code> if the user presses&#x000A;<code>escape</code>. <code>opts</code> is a table that contains the following fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>prompt</code>: <em>[optional]</em> The prompt displayed in the command line.</li>&#x000A;<li><code>title</code>: <em>[optional]</em> The title displayed in the command line title bar.</li>&#x000A;</ul>&#x000A;&#x000A;<p>Example:</p>&#x000A;<pre class="highlight moonscript"><span class="n">name</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">interact</span><span class="p">.</span><span class="n">read_text</span><span class="w"> </span><span class="ss">title:</span><span class="s1">'Name'</span><span class="p">,</span><span class="w"> </span><span class="ss">prompt:</span><span class="s1">'Enter name:'</span><span class="w">&#x000A;</span><span class="n">log</span><span class="p">.</span><span class="n">info</span><span class="w"> </span><span class="s1">'Hello '</span><span class="o">..</span><span class="n">name</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">name</span><span class="w">&#x000A;</span></pre>&#x000A;<h3 id="select">select <span class="arg-list">(opts)</span></h3>&#x000A;&#x000A;<p>Displays a list of options to the user and lets the user select one by using the&#x000A;<code>up</code> and <code>down</code> arrow keys and pressing <code>enter</code>. Also lets the user narrow down&#x000A;the options by typing something in the command line - the options list is then&#x000A;filtered to show only those items that match the entered text.</p>&#x000A;&#x000A;<p>Allows customization such as multiple columns, column headers, styling, user&#x000A;provided selection etc. These are described below.</p>&#x000A;&#x000A;<p>If the user presses <code>enter</code>, returns a table containing two fields - <code>selection</code>&#x000A;and <code>text</code>, where:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>selection</code> is the item selected by the user (or <code>nil</code> if <code>allow_new_value</code>&#x000A;was specified and the user specified option was selected - see <code>allow_new_value</code>&#x000A;below).</li>&#x000A;<li><code>text</code> is the command line text at the time <code>enter</code> was pressed.</li>&#x000A;</ul>&#x000A;&#x000A;<p>If the user presses <code>escape</code>, <code>nil</code> is returned.</p>&#x000A;&#x000A;<p><code>opts</code> is a table that specifies:</p>&#x000A;&#x000A;<ul>&#x000A;<li><p><code>items</code> or <code>matcher</code>: <em>[required]</em> One of <code>items</code> or <code>matcher</code> must be&#x000A;specified, but not both.</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>items</code> is a table containing a list of <em>items</em>, where each item represents&#x000A;one select-able option and can be either a string for a single column list, or a&#x000A;table for a multiple column list. When each item is a table, it contains a list&#x000A;of strings, one each for each column. Instead of a string, a&#x000A;<a href="ui/styled_text.html">StyledText</a> object can be used as well.</li>&#x000A;<li><code>matcher</code> is a function that accepts a string and returns a table of items&#x000A;similar to <code>items</code>. When called with the empty string, <code>matcher</code> should return a&#x000A;list of all options. As the user types text into the command line, the <code>matcher</code>&#x000A;function is called repeatedly and passed the typed text - it should return a&#x000A;filtered list of items matching the given text.</li>&#x000A;</ul></li>&#x000A;<li><p><code>prompt</code>: <em>[optional]</em> The prompt displayed in the command line.</p></li>&#x000A;<li><p><code>title</code>: <em>[optional]</em> The title displayed in the command line title bar.</p></li>&#x000A;<li><p><code>columns</code>: <em>[optional]</em> A table containing the header text and style for each&#x000A;column. Identical to the <code>columns</code> argument in the&#x000A;<a href="ui/styled_text.html#styledtext.for_table">StyledText.for_table</a> function.</p></li>&#x000A;<li><p><code>keymap</code>: <em>[optional]</em> An additional keymap to used for this interaction.</p></li>&#x000A;<li><p><code>on_selection_change</code>: <em>[optional]</em> A function callback that is called&#x000A;whenever the user changes the currently selected item (usually by using the&#x000A;arrow keys). The callback function is called with the three arguments&#x000A;<code>(selection, text, items)</code>, where:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>selection</code> is the newly selected item</li>&#x000A;<li><code>text</code> is the current text in the command line</li>&#x000A;<li><code>items</code> is the current (possibly filtered) list of items</li>&#x000A;</ul></li>&#x000A;<li><p><code>selection</code>: <em>[optional]</em> The item that is initially selected by default. This&#x000A;must be an item in the <code>items</code> list.</p></li>&#x000A;<li><p><code>hide_until_tab</code>: <em>[optional, default: false]</em> When set to <code>true</code>, the list of&#x000A;items is initially hidden and only displayed when the user presses <code>tab</code>.</p></li>&#x000A;<li><p><code>allow_new_value</code>: <em>[optional, default: false]</em> When set to <code>true</code>, allows the&#x000A;user to choose an option that is user specified and not available in the list of&#x000A;available items. The user does this by typing some text that does not exactly&#x000A;match any available option. This causes an additional option containing the&#x000A;user&rsquo;s text to be automatically added to the list of options. The user can then&#x000A;select this new option (identifiable because it shows &lsquo;New&rsquo; next to it) and&#x000A;press <code>enter</code>.</p></li>&#x000A;<li><p><code>reverse</code>: <em>[optional, default: false]</em> When set to <code>true</code>, the list is displayed reversed,&#x000A;i.e. the first item is displayed at the bottom and subsequent items above it.</p></li>&#x000A;</ul>&#x000A;&#x000A;<p>Examples:</p>&#x000A;&#x000A;<p>The following example displays a list of three items with a column header. It&#x000A;also lets the user specify a color that is not in the given list.</p>&#x000A;<pre class="highlight moonscript"><span class="n">color</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">interact</span><span class="p">.</span><span class="nb">select</span><span class="w">&#x000A;  </span><span class="ss">items:</span><span class="w"> </span><span class="p">{</span><span class="s1">'red'</span><span class="p">,</span><span class="w"> </span><span class="s1">'blue'</span><span class="p">,</span><span class="w"> </span><span class="s1">'green'</span><span class="p">}</span><span class="w">&#x000A;  </span><span class="ss">columns:</span><span class="w"> </span><span class="p">{{</span><span class="ss">header:</span><span class="w"> </span><span class="s1">'Color'</span><span class="p">}}</span><span class="w">&#x000A;  </span><span class="ss">allow_new_value:</span><span class="w"> </span><span class="kc">true</span><span class="w">&#x000A;</span><span class="k">if</span><span class="w"> </span><span class="n">color</span><span class="w">&#x000A;  </span><span class="k">if</span><span class="w"> </span><span class="n">color</span><span class="p">.</span><span class="n">selection</span><span class="w">&#x000A;    </span><span class="n">log</span><span class="p">.</span><span class="n">info</span><span class="w"> </span><span class="s1">'You selected:'</span><span class="o">..</span><span class="n">color</span><span class="p">.</span><span class="n">selection</span><span class="w">&#x000A;  </span><span class="k">else</span><span class="w">&#x000A;    </span><span class="n">log</span><span class="p">.</span><span class="n">info</span><span class="w"> </span><span class="s1">'You selected a new color:'</span><span class="o">..</span><span class="n">color</span><span class="p">.</span><span class="n">text</span><span class="w">&#x000A;</span></pre>&#x000A;<p>The following example displays a two column list. It also shows how string&#x000A;fields can be used in the items table. Unlike numerically indexed fields, string&#x000A;fields are not displayed, but they can be used to associate additional data with&#x000A;each item.</p>&#x000A;<pre class="highlight moonscript"><span class="n">action</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">interact</span><span class="p">.</span><span class="nb">select</span><span class="w">&#x000A;  </span><span class="ss">items:</span><span class="w"> </span><span class="p">{</span><span class="w">&#x000A;    </span><span class="p">{</span><span class="s1">'Run'</span><span class="p">,</span><span class="w"> </span><span class="s1">'Run this file'</span><span class="p">,</span><span class="w"> </span><span class="ss">cmd:</span><span class="w"> </span><span class="s1">'run'</span><span class="p">},</span><span class="w">&#x000A;    </span><span class="p">{</span><span class="s1">'Compile'</span><span class="p">,</span><span class="w"> </span><span class="s1">'Compile this file'</span><span class="p">,</span><span class="w"> </span><span class="ss">cmd:</span><span class="w"> </span><span class="s1">'compile'</span><span class="p">},</span><span class="w">&#x000A;  </span><span class="p">}</span><span class="w">&#x000A;</span><span class="k">if</span><span class="w"> </span><span class="n">action</span><span class="w">&#x000A;  </span><span class="k">if</span><span class="w"> </span><span class="n">action</span><span class="p">.</span><span class="n">selection</span><span class="p">.</span><span class="n">cmd</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s1">'run'</span><span class="w">&#x000A;    </span><span class="n">log</span><span class="p">.</span><span class="n">info</span><span class="w"> </span><span class="s1">'running...'</span><span class="w">&#x000A;  </span><span class="k">else</span><span class="w">&#x000A;    </span><span class="n">log</span><span class="p">.</span><span class="n">info</span><span class="w"> </span><span class="s1">'compiling...'</span><span class="w">&#x000A;</span></pre>&#x000A;<h3 id="select_buffer">select_buffer <span class="arg-list">(opts)</span></h3>&#x000A;&#x000A;<p>Lets the user select a buffer from a list of all buffers. <code>opts</code> is a table&#x000A;containing:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>prompt</code>: <em>[optional]</em> The prompt displayed in the command line. Default is no prompt.</li>&#x000A;<li><code>title</code>: <em>[optional]</em> The title displayed in the command line title bar. Default is &lsquo;Buffers&rsquo;.</li>&#x000A;</ul>&#x000A;&#x000A;<p>Returns the <a href="buffer.html">Buffer</a> selected by the user, or <code>nil</code> if the user&#x000A;presses <code>escape</code>.</p>&#x000A;&#x000A;<h3 id="select_directory">select_directory <span class="arg-list">(opts)</span></h3>&#x000A;&#x000A;<p>Lets the user select a directory. Displays sub directories in a completion list&#x000A;and allows the user to navigate the file system using either the completion list&#x000A;or typing a path in the command line.</p>&#x000A;&#x000A;<p><code>opts</code> is a table containing:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>title</code>: <em>[optional]</em> The title displayed in the command line title bar. Default is &lsquo;Directory&rsquo;.</li>&#x000A;<li><code>allow_new</code>: <em>[optional, default: false]</em> When <code>true</code>, allows the user to&#x000A;choose a nonexistent path by typing it in the command line and pressing enter.</li>&#x000A;</ul>&#x000A;&#x000A;<p>Returns the <a href="io/file.html">File</a> selected by the user, or <code>nil</code> if the user presses <code>escape</code>.&#x000A;Note that if <code>allow_new</code> was specified, the returned file object may refer to a&#x000A;nonexistent path.</p>&#x000A;&#x000A;<h3 id="select_file">select_file <span class="arg-list">(opts)</span></h3>&#x000A;&#x000A;<p>Lets the user select a file. Displays files in the completion list and allows&#x000A;the user to navigate the file system using the completion list or typing a path&#x000A;in the command line.</p>&#x000A;&#x000A;<p><code>opts</code> is a table containing:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>title</code>: <em>[optional]</em> The title displayed in the command line title bar.&#x000A;Default is &lsquo;File&rsquo;.</li>&#x000A;<li><code>allow_new</code>: <em>[optional, default: false]</em> When <code>true</code>, allows the user to&#x000A;choose a nonexistent path by typing it in the command line and pressing enter.</li>&#x000A;<li><code>directory_reader</code>: <em>[optional]</em> A callback function that is used for getting&#x000A;the list of files in any directory. The function should accept one argument - a&#x000A;<a href="io/file.html">File</a> object for a directory - and should return a list of <a href="io/file.html">File</a> objects for&#x000A;the contents of the given directory.</li>&#x000A;</ul>&#x000A;&#x000A;<p>Returns the <a href="io/file.html">File</a> selected by the user, or <code>nil</code> if the user presses <code>escape</code>.&#x000A;Note that if <code>allow_new</code> was specified, the returned file object may refer to a&#x000A;nonexistent path.</p>&#x000A;&#x000A;<h3 id="select_file_in_project">select_file_in_project <span class="arg-list">(opts)</span></h3>&#x000A;&#x000A;<p>Lets the user select a file from a completion list containing all files in the&#x000A;current project. <code>opts</code> is a table containing:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>title</code>: <em>[optional]</em> The title displayed in the command line title bar.&#x000A;Default is the project path.</li>&#x000A;</ul>&#x000A;&#x000A;<p>Returns the <a href="io/file.html">File</a> selected by the user, or <code>nil</code> if the user presses <code>escape</code>.</p>&#x000A;&#x000A;<h3 id="select_line">select_line<span class="arg-list">(opts)</span></h3>&#x000A;&#x000A;<p>Lets the user select a line from a list of source lines. <code>opts</code> is a table&#x000A;similar to the table accepted by <a href="#select">select</a>, with the following&#x000A;differences:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>items</code>, <code>matcher</code> and <code>on_selection_change</code> cannot be specified.</li>&#x000A;<li><code>lines</code> must be provided and should be a list of <a href="../spec/buffer_lines_spec.html#line-objects">Line</a> objects.</li>&#x000A;</ul>&#x000A;&#x000A;<p>If the user presses <code>enter</code>, returns a table containing:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>line</code>: the <a href="../spec/buffer_lines_spec.html#line-objects">Line</a> object selected by the user.</li>&#x000A;<li><code>text</code>: the command line text at the time <code>enter</code> was pressed.</li>&#x000A;<li><code>column</code>: the first position within line that matches the user entered text.</li>&#x000A;</ul>&#x000A;&#x000A;<p>If the user presses <code>escape</code>, <code>nil</code> is returned.</p>&#x000A;&#x000A;<h3 id="select_location">select_location<span class="arg-list">(opts)</span></h3>&#x000A;&#x000A;<p>Very similar to <a href="#select">select</a>, lets the user select an item from a list of&#x000A;options. In addition, it displays a preview of the currently selected option in&#x000A;the editor. Each item in <code>items</code> (or returned by <code>matcher</code>) must also have the&#x000A;following fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>file</code> or <code>buffer</code>: One of <code>file</code> or <code>buffer</code> must be provided. This specifies&#x000A;which file or buffer is previewed in the editor when this item is selected:&#x000A;&#x000A;<ul>&#x000A;<li><code>file</code>: A <a href="io/file.html">File</a> object.</li>&#x000A;<li><code>buffer</code>: A <a href="buffer.html">Buffer</a> object.</li>&#x000A;</ul></li>&#x000A;<li><code>line_nr</code>: The line number in <code>file</code> or <code>buffer</code> that is centered during the&#x000A;preview.</li>&#x000A;</ul>&#x000A;&#x000A;<h3 id="yes_or_no">yes_or_no <span class="arg-list">(opts)</span></h3>&#x000A;&#x000A;<p>Lets the user select either &lsquo;Yes&rsquo; or &lsquo;No&rsquo; as an answer to a question. Returns&#x000A;<code>true</code> if the user selects &lsquo;Yes&rsquo;, <code>false</code> if the user selects &lsquo;No&rsquo; and <code>nil</code> if&#x000A;the user presses <code>escape</code>. <code>opts</code> is table containing:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>prompt</code>: <em>[optional]</em> The prompt displayed in the command line. Default is no prompt.</li>&#x000A;<li><code>title</code>: <em>[optional]</em> The title displayed in the command line title bar. Default is no title.</li>&#x000A;</ul>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2015
            <a class='alert-link' href='https://github.com/nilnor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>
